 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qtsmban.gif){kind=small}
 (Disk 2).iso/pc/technical publications/quicktime/qtdevdocs/images/qt4api.gif)
QuickTime 4 Reference
| Previous | Chapter Contents | Chapter Top | Next |
This section contains several new functions to support modifier tracks, active segments, and video settings. These functions apply to all derived media handler components.
The MediaGSetActiveSegment function informs your derived media handlers of the current active segment.
pascal ComponentResult MediaGSetActiveSegment(
MediaHandler mh,
TimeValue activeStart,
TimeValue activeDuration);
Using the SetMovieActiveSegment function, an application can limit the time segment of the movie that will be used for play back. Derived media handlers are given the values for the active segment by the MediaGSetActiveSegment function called by the toolbox. Active segment information is usually only needed by media handlers that perform their own scheduling.
The MediaInvalidateRegion function updates the invalidated display region the next time MediaIdle is called.
pascal ComponentResult MediaInvalidateRegion(
MediaHandler mh,
RgnHandle invalRgn);
The MediaInvalidateRegion function is called by the toolbox when UpdateMovie or InvalidateMovieRegion is called with a region that intersects your media's track.
Derived media handlers need to implement MediaInvalidateRegion only if they can perform efficient updates on a portion of their display area.
If a media handler implements the MediaInvalidateRegion function, it is responsible for ensuring that the appropriate areas of the screen are updated on the next call to MediaIdle . If a media handler does not implement this function, the base media handler sets the mMustDrawflag the next time MediaIdle is called.
The MediaGetNextStepTime function searches for the next forward or backward step time from the given media time. The step time is the time of the next frame. This function allows a derived media handler to return the next step time from the specified media time.
pascal ComponentResult MediaGetNextStepTime(
MediaHandler mh,
short flags,
TimeValue mediaTimeIn,
TimeValue *mediaTimeOut,
Fixed rate);
The mechanism in QuickTime used for stepping backwards and forwards a frame at a time are the interesting time calls: GetMovieNextInterestingTime , GetTrackNextInterestingTime , and GetMediaNextInterestingTime . The normal method for stepping forward to the next frame is to use one of these calls to locate the time of the next visual sample. This works well for most media types, including video and text. Unfortunately, it does not work well for MPEG. QuickTime stores an entire MPEG stream as a single sample. Therefore stepping to the next sample would actually skip to the end of the entire sequence. To solve this problem, QuickTime 2.1 introduced a new flag, nextTimeStep , for the interesting time calls. This flag is specifically intended for stepping through frames.
The standard QuickTime movie controller has been updated to use this flag in place of the old nextTimeSample flag. The nextTimeStep flag works correctly for all media types including video and MPEG. To work correctly with MPEG, applications that implement stepping functionality should use this new flag.
See Inside Macintosh: QuickTime for more information on interesting times.
The MediaTrackReferencesChanged function notifies the derived media handler whenever the track references in the movie change.
pascal ComponentResult MediaTrackReferencesChanged (MediaHandler mh);
When an application creates, modifies, or deletes a track reference, the media handler's MediaTrackReferencesChanged function is called. When this function is called, a media handler should rebuild all information about track references and reset its values for all media inputs to their default values.
The MediaTrackPropertyAtomChanged function notifies the derived media handler whenever its media property atom has changed.
pascal ComponentResult MediaTrackPropertyAtomChanged (MediaHandler mh);
When an application modifies the media input map, the MediaSetTrackInputMap function provides the derived media handler with the updated input map.
pascal ComponentResult MediaSetTrackInputMapReference(
MediaHandler mh,
QTAtomContainer inputMap);
When the MediaSetTrackInputMapReference function is called, the media handler should store the updated input map and recheck the types of all inputs, if it is caching this information. The input map reference passed to this function should not be disposed of or modified by the media handler.
The MediaGetSampleDataPointer function allows a derived media handler to obtain a pointer to the sample data for a particular sample number, the size of that sample, and the index of the sample description associated with that sample.
pascal ComponentResult MediaGetSampleDataPointer(
MediaHandler mh,
long sampleNum,
Ptr *dataPtr,
long *dataSize,
long *sampleDescIndex);
The MediaGetSampleDataPointer function returns a pointer to the data for a particular sample number from a movie data file.
This function provides access to the base media handler's caching services for sample data. It is a service provided by the base media handler for its clients.
Each call to MediaGetSampleDataPointer must be balanced by a call to MediaReleaseSampleDataPointer or the memory will not be released. MediaGetSampleDataPointer generally provides better overall performance than GetMediaSample .
The MediaReleaseSampleDataPointer function balances calls to MediaGetSampleDataPointer to release the memory. This function should be used only by derived media handlers.
pascal ComponentResult MediaReleaseSampleDataPointer(
MediaHandler mh,
long sampleNum);
The MediaCompare function allows a media handler to determine whether the Movie Toolbox should allow one track to be pasted into another. MediaCompare is provided with a reference to the media with which it should be compared.
pascal ComponentResult MediaCompare(
MediaHandler mh,
Boolean *isOK,
Media srcMedia,
ComponentInstance srcMediaComponent);
The MediaSetVideoParam function enables you to dynamically adjust the brightness, contrast, hue, sharpness, saturation, black level, and white level of a video image.
pascal ComponentResult MediaSetVideoParam(
MediaHandler mh,
long whichParam,
unsigned short *value);
The MediaSetVideoParam and MediaGetVideoParam functions are currently used by the MPEG media handler.
See "Media Video Parameters" for the constants and values you can use for the whichParam and value parameters.
The MediaGetVideoParam function enables you to retrieve the value of the brightness, contrast, hue, sharpness, saturation, black level, or white level of a video image.
pascal ComponentResult MediaGetVideoParam(
MediaHandler mh,
long whichParam,
unsigned short *value);
The MediaSetNonPrimarySourceData function allows a media handler to support receiving media data from other media handlers.
pascal ComponentResult MediaSetNonPrimarySourceData(
MediaHandler mh,
long inputIndex,
long dataDescriptionSeed,
Handle dataDescription,
void *data,
long dataSize,
ICMCompletionProcRecordPtr asyncCompletionProc,
UniversalProcPtr transferProc,
void *refCon);
There are two tasks required to support modifier tracks in a derived media handler: sending and receiving. The base media handler takes care of sending data for all its clients. Therefore, authors of derived media handlers do not usually need to implement sending data support.
Receiving data is a more complex situation. The base media handler takes care of input types that it understands. The base media handler supports the following types of data:
kTrackModifierTypeMatrix
kTrackModifierTypeGraphicsMode
kTrackModifierTypeClip
kTrackModifierTypeVolume
kTrackModifierTypeBalance
If a media handler wants to support receiving other types of data it must implement the MediaSetNonPrimarySourceData routine. MediaSetNonPrimarySourceData is called by modified tracks to supply the current data for each input. All unrecognized input types should be delegated to the base media handler so that they can be handled.
The following is a basic shell implementation of a derived media handler's MediaSetNonPrimarySourceData function. Note that your derived media handler must delegate all input types it does not handle to the base media handler.
pascal ComponentResult MySetNonPrimarySourceData( MyGlobals store,
long inputIndex, long dataDescriptionSeed, Handle dataDescription,
void *data, long dataSize,
ICMCompletionProcRecordPtr asyncCompletionProc,
UniversalProcPtr transferProc, void *refCon )
{
ComponentResult err = noErr;
QTAtom inputAtom;
QTAtom typesAtom;
long inputType;
// determine what kind of input this is
inputAtom = QTFindChildByID(store->inputMap,
kParentAtomIsContainer, kTrackModifierInput, inputIndex, nil);
if (!inputAtom) {
err = cannotFindAtomErr;
goto bail;
}
typesAtom = QTFindChildByID(store->inputMap, inputAtom,
kTrackModifierType, 1, nil);
err = QTCopyAtomDataToPtr(store->inputMap, typesAtom, false,
sizeof(inputType), &inputType, nil);
if (err) goto bail;
switch(inputType) {
case kMyInputType:
if (data == nil) {
// no data, reset to default value
}
else {
// use this data
// when done, notify caller we're done with this data
if (asyncCompletionProc)
CallICMCompletionProc(
asyncCompletionProc->completionProc,
noErr, codecCompletionSource | codecCompletionDest,
asyncCompletionProc->completionRefCon);
}
break;
default:
err = MediaSetNonPrimarySourceData(store->delegateComponent,
inputIndex, dataDescriptionSeed, dataDescription, data,
dataSize, asyncCompletionProc, transferProc, refCon);
break;
}
bail:
return err;
}
The MediaGetOffscreenBufferSize function determines the dimensions of the offscreen buffer.
pascal ComponentResult MediaGetOffscreenBufferSize(
MediaHandler mh,
Rect *bounds,
short depth,
CTabHandle ctab);
Before the base media handler allocates an offscreen buffer for your derived media handler, it calls your MediaGetOffscreenBufferSize function. The depth and color table used for the buffer are also passed. When this function is called, the bounds parameter specifies the size that the base media handler intends to use for your offscreen buffer. You can modify this as appropriate before returning. This capability is useful if your media handler can draw only at particular sizes. It is also useful for implementing antialiased drawing; you can request a buffer that is larger than your destination area and have the base media handler scale the image down for you.
The MediaSetHints function implements the appropriate behavior for the various media hints such as scrub mode and high-quality mode.
pascal ComponentResult MediaSetHints(
MediaHandler mh,
long hints);
The MediaGetName function returns the name of the media type. For example, the video media handler returns the string 'video' .
pascal ComponentResult MediaGetName(
MediaHandler mh,
Str255 name,
long requestedLanguage,
long *actualLanguage);
| Previous | Chapter Contents | Chapter Top | Next |